Skip to content

Name the Python extension after what it contains - #21816

Merged
shoumikhin merged 702 commits into
mainfrom
gh/shoumikhin/108/head
Aug 20, 2026
Merged

Name the Python extension after what it contains#21816
shoumikhin merged 702 commits into
mainfrom
gh/shoumikhin/108/head

Conversation

@shoumikhin

@shoumikhin shoumikhin commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

The compiled Python extension in the wheel was called _portable_lib. That name
is misleading in two ways. "Portable" is the name of a kernel set in this project,
the portable kernels, and this file does not contain them: it holds the Python
bindings for the runtime. "Lib" says nothing, since every shared object is a
library. Someone looking for the portable kernels finds the Python bindings
instead, and someone looking for the bindings has no reason to open a file named
after kernels.

Rename it to _C, which is the usual name for a package's compiled C extension
and what PyTorch calls the same thing (torch/_C.cpython-*.so). The package path
already says pybindings, as in executorch.extension.pybindings, so a name like
_pybindings would repeat itself while _C reads as "this package's C
extension".

The documented import path is unaffected. Applications import the public wrapper:

from executorch.extension.pybindings import portable_lib

That wrapper re-exports everything from the compiled module and keeps its name, so
code using it continues to work.

Code that imports the private module directly does break, and that pattern is in
real use despite the module being documented as experimental and subject to change.
No Python alias is added for the old name, since keeping the name reachable would
leave in place the thing this change exists to remove; such a caller moves to the
public wrapper.

The CMake target of that name is also gone, and this is a compatibility break worth
stating plainly. Version 1.4.1 published it, as add_library(_portable_lib STATIC IMPORTED), and put it in EXECUTORCH_LIBRARIES. A project that names it directly no
longer configures and should link executorch::runtime instead.

Keeping the name was tried and dropped. Aliasing it to the runtime looked compatible
and was not: the published target was mutable and demanded C++20, and
$<TARGET_FILE:> on it named the extension, so an alias silently moved the consumer
to C++17, changed the file that expression resolves to, and made set_property on it
a hard error because an alias is immutable. Pointing it back at the extension is not an
option either: that file holds unresolved interpreter symbols, so a plain C++
application that links it fails to link or dies at startup.

What a consumer using the documented EXECUTORCH_LIBRARIES variable gets also changes,
for the better. In 1.4.1 that variable held the Python extension, so linking it from
C++ could not work. It now holds the runtime and the kernel and backend libraries,
which is what such a project wanted.

Test plan:

Built a wheel and confirmed the shipped file is named for the new module:

extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so

Installed that wheel into a fresh environment and checked both the public wrapper
and the private module load, then exported and ran a model through the Python
bindings:

public wrapper works: True
module name         : executorch.extension.pybindings._C
exported symbols    : 22

Also grepped the tree. The only place the old extension name survives is the
package config, where the compatibility aliases keep it on purpose. The other
matches name the portable kernels library, which is a different thing.

@shoumikhin

shoumikhin commented Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Stack from ghstack (oldest at bottom):

@pytorch-bot

pytorch-bot Bot commented Aug 13, 2026

Copy link
Copy Markdown

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21816

Note: Links to docs will display an error until the docs builds have been completed.

⏳ No Failures, 33 Pending

As of commit dfb5eb1 with merge base 4724088 (image):
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Aug 13, 2026
shoumikhin added a commit that referenced this pull request Aug 13, 2026
The compiled Python extension in the wheel was called `_portable_lib`. That name
is misleading in two ways. "Portable" is the name of a kernel set in this project,
the portable kernels, and this file does not contain them: it holds the Python
bindings for the runtime. "Lib" says nothing, since every shared object is a
library. Someone looking for the portable kernels finds the Python bindings
instead, and someone looking for the bindings has no reason to open a file named
after kernels.

Rename it to `_C`, which is the usual name for a package's compiled C extension
and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path
already says `pybindings`, as in `executorch.extension.pybindings`, so a name like
`_pybindings` would repeat itself while `_C` reads as "this package's C
extension".

Nothing user facing changes. Applications import the public wrapper:

```python
from executorch.extension.pybindings import portable_lib
```

That wrapper re-exports everything from the compiled module and keeps its name, so
existing code continues to work. Only the private module behind it is renamed, and
it was already documented as experimental and subject to change.

Test plan:

Built a wheel and confirmed the shipped file is named for the new module:

```
extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so
```

Installed that wheel into a fresh environment and checked both the public wrapper
and the private module load, then exported and ran a model through the Python
bindings:

```
public wrapper works: True
module name         : executorch.extension.pybindings._C
exported symbols    : 22
```

Also grepped the tree to confirm no build file, test, or comment still names the
old module.

ghstack-source-id: 20f23fe
ghstack-comment-id: 5282557165
Pull-Request: #21816
shoumikhin added a commit that referenced this pull request Aug 13, 2026
The compiled Python extension in the wheel was called `_portable_lib`. That name
is misleading in two ways. "Portable" is the name of a kernel set in this project,
the portable kernels, and this file does not contain them: it holds the Python
bindings for the runtime. "Lib" says nothing, since every shared object is a
library. Someone looking for the portable kernels finds the Python bindings
instead, and someone looking for the bindings has no reason to open a file named
after kernels.

Rename it to `_C`, which is the usual name for a package's compiled C extension
and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path
already says `pybindings`, as in `executorch.extension.pybindings`, so a name like
`_pybindings` would repeat itself while `_C` reads as "this package's C
extension".

Nothing user facing changes. Applications import the public wrapper:

```python
from executorch.extension.pybindings import portable_lib
```

That wrapper re-exports everything from the compiled module and keeps its name, so
existing code continues to work. Only the private module behind it is renamed, and
it was already documented as experimental and subject to change.

Test plan:

Built a wheel and confirmed the shipped file is named for the new module:

```
extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so
```

Installed that wheel into a fresh environment and checked both the public wrapper
and the private module load, then exported and ran a model through the Python
bindings:

```
public wrapper works: True
module name         : executorch.extension.pybindings._C
exported symbols    : 22
```

Also grepped the tree to confirm no build file, test, or comment still names the
old module.

ghstack-source-id: 5386d2f
ghstack-comment-id: 5282557165
Pull-Request: #21816
shoumikhin added a commit that referenced this pull request Aug 13, 2026
The compiled Python extension in the wheel was called `_portable_lib`. That name
is misleading in two ways. "Portable" is the name of a kernel set in this project,
the portable kernels, and this file does not contain them: it holds the Python
bindings for the runtime. "Lib" says nothing, since every shared object is a
library. Someone looking for the portable kernels finds the Python bindings
instead, and someone looking for the bindings has no reason to open a file named
after kernels.

Rename it to `_C`, which is the usual name for a package's compiled C extension
and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path
already says `pybindings`, as in `executorch.extension.pybindings`, so a name like
`_pybindings` would repeat itself while `_C` reads as "this package's C
extension".

Nothing user facing changes. Applications import the public wrapper:

```python
from executorch.extension.pybindings import portable_lib
```

That wrapper re-exports everything from the compiled module and keeps its name, so
existing code continues to work. Only the private module behind it is renamed, and
it was already documented as experimental and subject to change.

Test plan:

Built a wheel and confirmed the shipped file is named for the new module:

```
extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so
```

Installed that wheel into a fresh environment and checked both the public wrapper
and the private module load, then exported and ran a model through the Python
bindings:

```
public wrapper works: True
module name         : executorch.extension.pybindings._C
exported symbols    : 22
```

Also grepped the tree to confirm no build file, test, or comment still names the
old module.

ghstack-source-id: e6925ec
ghstack-comment-id: 5282557165
Pull-Request: #21816
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
[ghstack-poisoned]
@linux-foundation-easycla

Copy link
Copy Markdown

CLA Not Signed

@github-actions

Copy link
Copy Markdown

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ciflow/binaries/all Release PRs with this label will build wheels for all python versions ciflow/binaries ciflow/cuda ciflow/trunk CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants